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4. Flow of Control 

l.isp provides a variety of structures for flow of control. 

Function application is the basic method for construction of programs. Operations arc written 
as the application of a function to its arguments. Usually. Lisp programs are written as a large 
collection of small functions, each of which implements a simple operation. These functions 
operate by calling one another, and so larger operations arc defined in terms of smaller ones. 

A function may always call itself in Lisp. The calling of a function by itself is known as 
recursion: it is analogous to mathematical induction. 

The performing of an action repeatedly (usually with some changes between repetitions) is 
called iteration, and is provided as a basic control structure in most languages. The do statement 
of PL/I, the for statement of ALGOL/60, and so on arc examples of iteration primitives. Lisp 
provides two general iteration facilities: do and loop, as well as a variety of special-purpose 
iteration facilities, (loop is sufficiently complex that it is explained in its own chapter later in the 
manual; sec page 350.) 

A conditional construct is one which allows a program to make a decision, and do one thing 
or another based on some logical condition. Lisp provides the simple one-way conditionals and 
and or, the simple two-way conditional if, and more general multi-way conditionals such as cond 
and selectq. The choice of which form to use in 'any particular situation is a matter of personal 
taste and style. 

There are some non-local exit control structures, analogous to the leave, exit, and escape 
constructs in many modern languages. Zctalisp provides for both static (lexical) non-local exits 
with block and return-from and dynamic non-local exits with catch and throw. Another kind of 
non-local exit is the goto, provided by the tagbody and go constructs. 

Zctalisp also provides a coroutine capability, explained in the section on slack-groups (chapter 
13, page 256), and a multiple-process facility (see chapter 29, page 682). There is also a facility 
for generic function calling using message passing; see chapter 21, page 401. 

4.1 Compound Statements 

progn body... Special form 

The body forms are evaluated in order from left to right and the value of the last one is 
returned, progn is the primitive control structure construct for "compound statements". 
Example: 

(foo (cdr a) 

(progn (setq b (extract frob)) 

(car b)) 
(cadr b)) 
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I ambda-expressions. cond forms, do forms, and many other control structure forms use 
progn implicitly, that is, they allow multiple forms in their bodies. 

progl first- form body... Special form 

progl is similar to progn, but it returns the value of its first form rather than its last. It 
is most commonly used to evaluate an expression with side effects, and return a value 
which must be computed before the side effects happen. 
Hxamplc: 

(setq x (progl y (setq y x))) 
interchanges the values of the variables x and ;•. progl never returns multiple values. 

prog2 first-form second-form body... Special form 

prog2 is similar to progn and progl, but it returns its second form. It is included 
largely for compatibility with old programs. 

4.2 Conditionals 

1f Special form 

if is the simplest conditional form. The "if-then" form looks like: 

( i f predicate-form then- form ) 
predicate-form is evaluated, and if the result is non-nil, the then-form is evaluated and its 
result is returned. Otherwise, nil is returned. 

In the "if-then-clsc" form, it looks like 

(if predicate-form then- form else- form) 
predicate-fonn is evaluated, and if the result h non-nil, the then-form is evaluated and its 
result is returned. Otherwise, the else-form is evaluated and its result is returned. 

If there are more than three subforms, if assumes you want more than one else-form; if 
the predicate returns nil, they are evaluated sequentially and the result of the last one is 
returned. 

when condition body... Macro 

If condition evaluates to something non-nil, the body is executed and its valuc(s) returned. 
Otherwise, the value of the when is nil and the body is not executed. 

unless condition body... Macro 

If condition evaluates to nil, the body is executed and its value(s) returned. Otherwise, 
the value of the unless is nil and the body is not executed. 

cond Special form 

The cond special form consists of the symbol cond followed by several clauses. Each 
clause consists of a predicate form, called the condition, followed by zero or more body 
forms. 
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(cond {condition body body .. .) 
(condition) 
( condition body . . . ) 
... ) 

The idea is that each clause represents a case which is selected if its condition is satisfied 
and the conditions of all preceding clauses were not satisfied. When a clause is selected, 
its body forms are evaluated. 

cond processes its clauses in order from left to right. First, the condition of the current 
clause is evaluated. If the result is nil, cond advances to the next clause. Otherwise, the 
edi of the clause is treated as a list of body forms which arc evaluated in order from left 
to right. After evaluating the body forms, cond returns without inspecting any remaining 
clauses. The value of the cond form is the value of the last body form evaluated, or the 
value of the condition if there were no body forms in the clause. If cond runs out of 
clauses, that is, if every condition evaluates to nil, and thus no case is selected, the value 
of die cond is nil. 
Example: 



(cond ((zerop x) 
( + y 3)) 

((null y) 
(setq y 4) 
(cons x z)) 

(z) 



(t 
105) 



) 



; First clause: 

; (zerop x ) is the condition. 

; ( + y 3 ) is the body. 

; A clause with 2 body forms: 

; this 

; and this. 

; A clause with no body forms: the condition is 

;justz. If z is non-nil, it is returned. 

;A condition oft 

; is always satisfied. 

; This is the end of the cond. 



cond-every Macro 

cond -every has the same syntax as cond, but executes every clause whose condition is 
satisfied, not just die first. If a condition is the symbol otherwise, it is satisfied if and 
only if no preceding condition is satisfied. The value returned is the value of the last 
body form in die last clause whose condition is satisfied. Multiple values arc not returned. 

and form... Special form 

and evaluates the fotws one at a time, from left to right. If any form evaluates to nil, 
and immediately returns nil without evaluating the remaining forms. If all the forms 
evaluate to non-nil values, and returns the value of the last form. 

and can be used in two different ways. You can use it as a logical and function, because 
it returns a true value only if all of its arguments are true: 
(if (and socrates-is-a-person 

al 1-people-are-mortal) 
(setq socrates-is-mortal t)) 
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Because the order of evaluation is well-defined, you can do 
(if (and (boundp 'x) 
(eq x 'foo)) 
( setq y 'bar) ) 
knowing that the x in the eq form will not be evaluated if x is found to be void. 

You can also use and as a simple conditional form: 
(and (setq temp (assq x y)) 

(rplacd temp z)) 
(and bright-day 
glorious-day 

(princ "It is a bright and glorious day.")) 
but when is usually preferable. 

Note: (and) => t, which is the identity for the and operation. 

or form... Special form 

or evaluates the forms, one by one from left to right. If a form evaluates to nil, or 
proceeds to evaluate the next form. If dicrc arc no more forms, or returns nil. But if a 
form evaluates to a non-nil value, or immediately returns that value without evaluating 
any remaining forms. 

As with and, or can be used cither as a logical or function, or as a conditional: 

(or it-is-fish it-is-fowl) 

(or it-is-fish it-is-fowl 

(print "It is neither fish nor fowl.") 

but it is often possible and cleaner to use unless in the latter case. 

Note: (or) => nil, the identity for this operation. 

selectq Macro 

case Macro 

caseq Macro 

selectq is a conditional which chooses one of its clauses to execute by comparing the 

value of a form against various constants using eql. Its form is as follows: 

(selectq key-form 

(test body. . . ) 

(test body. . . ) 

(test body. . . ) 

The first thing selectq does is to evaluate key-form; call the resulting value key. Then 
selectq considers each of the clauses in turn. If key matches the clause's test, the body 
of the clause is evaluated, and selectq returns the value of the last body form. If there 
are no matches, selectq returns nil. 
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A test may be any of: 

1 ) A symbol 

2) A number 

3) A list 

4) t or otherwise 



If the key is eql to the symbol, it matches. 

If the key is eql to the number, it matches, key must 
have the same type and the same value as the number. 

If the key is eql to one of the elements of the list, then it 
matches. The elements of the list should be symbols or 
numbers. 

The symbols t and otherwise arc special tests which match 
anything. Hither symbol may be used, it makes no 
difference; t is mainly for compatibility with Maclisp's 
caseq construct. -To be useful, this should be die last 
clause in the selectq. 



Example: 

(selectq x 

(foo (do-this)) 
(bar (do-that)) 

((baz quux mum) ( do-the-other-thing) ) 
(otherwise (ferror nil "Never heard of ~S" x))) 
is equivalent to 

(cond ((eq x 'foo) (do-this)) 
((eq x 'bar) (do-that)) 

((memq x '(baz quux mum)) (do-the-other-thing)) 
(t (ferror nil "Never heard of ~S" x))) 

Note 'that. the tests are not evaluated; if you want them to be evaluated use select rather 
than selectq. 

case is the Common Lisp name for this construct, caseq is the Maclisp name; it 
identical to selectq, which is not totally compatible with Maclisp, because selectq accepts 
otherwise as well as t where caseq would not accept otherwise, and because Maclisp 
does some error-checking that selectq docs not. Maclisp programs that use caseq work 
correctly so long as they don't use the symbol otherwise as a key. 

ecase key- form clauses... Macro 

Like case except dial an uncorrectable error is signaled if every clause fails, t or 
otherwise clauses arc not allowed. 

cease place clauses... Macro 

Like ecase except that the error is correctable. The first argument is called place because 
it must be setfable. If die user proceeds from the error, a new value is read and stored 
into place; then the clauses arc tested again using the new value. Errors repeat until a 
value is specified which makes some clause succeed. 

Also see defselect (page 236), a special form for defining a function whose body is like a 
selectq. 
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select Macro 

select is like selectq, except that the elements of the tests are evaluated before they arc 
used. 

This creates a syntactic ambiguity: if (bar baz) is seen the first clement of a clause, is it 
a list of two forms, or is it one form? select interprets it as a list of two forms. If you 
want to have a clause whose test is a single form, and that form is a list, you have to 
write it as a list of one form. 
Hxample: 

(select (frob x) 
(foo 1) 
((bar baz) 2) 
( ( (current-f rob) ) 4) 
(otherwise 3)) 
is equivalent to 

(let ((var (frob x))) 
(cond ( (eq var foo) 1) 

((op (eq var bar) (eq var baz)) 2) 
((eq var (current-f rob) ) 4) 
(t 3))) 

selector Macro 

selector is like select, except that you get to specify the function used for the 
comparison instead of eq. For example, 
(selector (frob x) equal 

(('(one . two)) (frob-one x)) 
(('(three . four)) (frob-three x)) 
(otherwise (frob-any x))) 
is equivalent to 

(let ((var (frob x)))' 

(cond ((equal var '(one . two)) (frob-one x)) 

((equal var '(three . four)) (frob-three x)) 
(t (frob-any x)))) 

select-match Macro 

select- match is like select but each clause can specify a pattern to match the key 
against. The general form of use looks like 
(select-match key-form 
(pattern condition body. . . ) 
(pattern condition body. . .) 

(otherwise body. . . )) 
The value of key-form is matched against the patterns one at a time until a match 
succeeds and the accompanying condition evaluates to something non-nil. At this point the 
body of that clause is executed and its valuc(s) returned. If all the patterns/conditions fail, 
the body of the otherwise clause (if any) is executed. A pattern can test the shape of the 
key object, and set variables which the condition form can refer to. All the variables set 
by the patterns are bound locally to the select-match form. 
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The patterns arc matched using list-match- p (page 92). 

Kxamplc: 

(select-match '(a b c) 

( ' ( ,x b , x) t (vector x) ) 

('((,x ,y) b . .ignore) t (list x y)) 

('(,x b ,y) (symbolp x) (cons x y)) 

(otherwise 'lose-big)) 
returns (a . c), having checked (symbolp 'a). The first clause matches only if the there 
arc three elements, the first and third elements arc equal and the second element is b. 
The second matches only if the first element is a list of length two and the second 
clement is b. The third clause accepts any list of length three whose second clement is b. 
The fourth clause accepts anything that did not match the previous clauses. 

select-match generates highly optimized code using special instructions. 

dispatch Macro 

(dispatch byte- specifier number clauses...) is the same as select (not selectq), but die key 
is obtained by evaluating (Idb byte- specifier number), byte-specifier and number arc both 
evaluated. Byte specifiers and Idb arc explained on page 155. 
Example: 

(princ (dispatch (byte 2 13) cat-type 
(0 "Siamese.") • 
(1 "Persian.") 
(2 "Alley.") 
(3 (ferror nil 

"~S is not a known cat type." 
cat-type)))) 

It is not necessary to include all possible values of the byte which is dispatched on. 

selectq-every Macro 

selectq -every has the same syntax as selectq, but, like cond -every, executes every 
selected clause instead of just the first one. If an otherwise clause is present, it is 
selected if and only if no preceding clause is selected. The value returned is the value of 
the last form in the last selected clause. Multiple values are not returned. Example: 
(selectq-every animal 

((cat dog) (setq legs 4)) 

((bird man) (setq legs 2)) 

((cat bird) (put-in-oven animal)) 

((cat dog man) (beware-of animal))) 
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4.2.1 Comparison Predicates 

eq x y 

(eq .v v) => t if and only if x and y arc the same object. It should be noted that things 
that print the same arc not necessarily eq to each other. In particular, numbers with the 
same value need not be eq, and two similar lists are usually not eq. 
I examples: 

(eq 'a *b) => nil 

(eq 'a 'a) => t 

(eq (cons 'a 'b) (cons 'a 'b)) => nil 

(setq x (cons 'a 'b)) (eq x x) => t 

Note that in Zctalisp equal fixnums arc eq; this is not true in Maclisp. Hquality docs not 
imply eq-ncss for other types of numbers. To compare numbers, use =; sec page 139. 

neq x y 

(neq x y) = (not (eq jc y)). This is provided simply as an abbreviation for typing 

convenience. 

eql x y 

eql is the same as eq except that if x and y arc numbers of the same type they are eql 

if they arc = . 

equal x y 

The equal predicate returns t if its arguments arc similar (isomorphic) objects. Two 
numbers arc equal if they have the same value and type (for example, a float is never 
equal to a fixnum, even if = is true of them). For conscs, equal is defined recursively 
as the two cars being equal and the two cdrs being equal. Two strings arc equal if they 
have the same length, and the characters composing them arc the same; sec string = , 
page 214. Alphabetic case is significant. All other objects are equal if and only if they 
are eq. Thus equal could have been defined by: 
(defun equal (x y) 
(cond ((eq x y) t) 

((and (numberp x) (numberp y)) 

(= x y)) 
((and (stringp x) (stringp y)) 

(string-equal x y)) 
((and (consp x) (consp y)) 
(and (equal (car x) (car y)) 

(equal (cdr x) (cdr y)))))) 

As a consequence of the above definition, it can be seen that equal may compute forever 
when applied to looped list structure. In addition, eq always implies equal; that is, if 
(eq a b) then (equal a b). An intuitive definition of equal (which is not quite correct) is 
that two objects are equal if they look the same when printed out. For example: 
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(setq a '(12 3)) 

(setq b '(1 2 3)) 

(eq a b) => nil 

(equal a b) => t 

(equal "Foo" Too") => nil 

equal p x y 

equalp is a broader kind of equality than equal. Two objects that arc equal arc always 
equalp. In addition, numbers of different types arc equalp if they arc = . Two character 
objects arc equalp if they arc char-equal (that is, they arc compared ignoring font, case 
and mcta bits). 

Two arrays of any sort arc equalp if they have the same dimensions and corresponding 
elements are equalp. In particular, this means that two strings arc equalp if they match 
ignoring case and font information. 

(equalp "Foo" "foo") => t 

(equalp ' 1 *1.0) => t 

(equalp '(1 "Foo") '(1.0 "foo")) => t 

Because equalp is a Common Lisp function, it regards a string as having character objects 
as its elements: 

(equalp "Foo" #(#*/F #*/o'#*/o).) => t 

(equalp "Foo" #(#/F #/o #/o)) => nil 

not x 
null x 

not returns t if x is nil, else nil. null is the same as not; both functions arc included for 
the sake of clarity. Use null to check whether something is nil; use not to invert the 
sense of a logical value. Some people prefer to distinguish between nil as falsehood and 
nil as the empty list by writing: 

(cond ((not (null 1st)) ... ) 

( ... )) 
rather than 
(cond (1st ... ) 

( ... )) 

There is no loss of efficiency, since these compile into exactly the same instructions. 

4.3 Iteration 

do Special form 

The do special form provides a simple generalized iteration facility, with an arbitrary 
number of "index variables" whose values arc saved when the do is entered and restored 
when it is left, i.e. they arc bound by the do. The index variables are used in the 
iteration performed by do. At the beginning, they arc initialized to specified values, and 
then at the end of each trip around the loop the values of the index variables are 
changed according to specified rules, do allows the programmer to specify a predicate 
which determines when the iteration will terminate. The value to be returned as the result 
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of the form may, optionally, be specified. 

do comes in two varieties, new-style and old-style. The old-style do is obsolete and exists 
for Maclisp compatibility only. The more general, "new-style" do looks like: 
(do ((var init repeat) ..'.)■ 

( end- lest exit-form . . . ) 

body. . . ) 

The first item in the form is a list of zero or more index variable specifiers. Kach index 
variable specifier is a list of the name of a variable var, an initial value form mil, which 
defaults to nil if it is omitted, and a repeat value form repeal. If repeal is omitted, the 
var is not changed between repetitions. If inii is omitted, the var is initialized to nil. 

An index variable specifier can also be just the name of a variable, rather than a list. In 
this case, the variable has an initial value of nil, and is not changed between repetitions. 

All assignment to the index variables is done in parallel. At the beginning of the first 
iteration, all the hut forms arc evaluated, then die vars are bound to the values of the 
mil forms, their old values being saved in the usual way. Note that the itiit forms arc 
evaluated before die vars arc bound, i.e. lexically outside of the do. At the beginning of 
each succeeding iteration those vars that have repeal fonns get set to the values of dieir 
respective repeal forms. Note that all the repeal forms are evaluated before any of the 
vars is set. • 

The second element of die do-form is a list of an end-testing predicate form end-test, and 
zero or more forms, called the exit-forms. This resembles a cond clause. At the 
beginning of each iteration, after processing of die variable specifiers, the end-test is 
evaluated. If die result is nil, execution proceeds with die body of the do. If the result 
is not nil, the exit-fonns are evaluated from left to right and dicn do returns. The value 
of the do is the value of die last exit-form, or nil if there were no exit- forms (not the 
value of the end- test, as you might expect by analogy with cond). 

Note that the end- lest gets evaluated before die first time the body is evaluated, do first 
initializes the variables from the init fonns, dien it checks the end-test, dicn it processes 
die body, dicn it deals with the repeat forms, dien it tests the end- test again, and so on. 
If die end -test returns a non-nil value the first time, dicn die body is not executed. 

If the second element of the form is nil, there is no end-test nor exit-forms, and the body 
of die do is executed only once. In diis type of do it is an error to have repeats. This 
type of do is no more powerful dian let; it is obsolete and provided only for Maclisp 
compatibility. 

If the second clement of the form is (nil), the end-test is never true and there are no 
exit-forms. The body of the do is executed over and over. The resulting infinite loop can 
be terminated by use of return or throw. 

do implicitly creates a block with name nil, so return can be used lexically within a do 
to exit it immediately. This unbinds the do variables and the do form returns whatever 
values were specified in die return form. Sec section 4.4, page 75 for more information 
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on these matters. The body of the do is actually treated as a tagbody, so that it may 

contain go tags (see section 4.5, page 78), but this usage is discouraged as it is often 

unclear. 

l-lxamplcs of the new form of do: 

(do ((i (1+ i)) ; This is just the same as the above example, 

(n (array-length foo-array))) 
( ( = i n ) ) ; but written as a new-style do. 

(aset foo-array i)) ; Note how the setq is avoided. 

(do ((z list (cdr z)) ;/. starts as list and is cdr'd each time. 

(y other-list) ;y starts as other- list, and is unchanged by the do. 
( x ) ; x starts as nil and is not changed by the do. 

w ) ; w starts as nil and is not changed by the do. 

(nil) ; The end-test is nil, so this is an infinite loop. 

body) ; Presumably the body uses return somewhere. 

The construction 

(do ( (x e (cdr x) ) 
(oldx x x)) 
((null x)) 
body) 
exploits parallel assignment to index variables. On the first iteration, the value of oldx is 
whatever value x had before the do was entered. On succeeding iterations, oldx contains 
the value that x had on the previous iteration. 

The body of a do may contains no forms at all. Very often an iterative algorithm can be 
most clearly expressed entirely in the repeals and exit-forms of a new-style do, and the 
body is empty. For example, 

(do ((x x (cdr x)) 
(y y (cdr y)) 

(z nil (cons (f x y) z))) ; exploits parallel assignment, 
((or (null x) (null y)) 

(nreversez)) ; typical use of nreverse. 

) ;no do-body required, 
is like (maplist 'f x y) (see page 84). 

The old-style do exists only for Maclisp compatibility. It looks like: 

(do var in it repeat end- test body...) 
The first time through the loop var gets the value of the foil form; the remaining times 
through the loop it gets the value of the repeat form, which is re-evaluated each time. 
Note that the init form is evaluated before var is bound, i.e. lexically outside of the do. 
Each time around the loop, after var is set, end-test is evaluated. If it is non-nil, the do 
finishes and returns nil. If the end-test evaluated to nil, the body of the loop is executed. 
As with the new-style do, return and go may be used in the body, and they have the 
same meaning. 

Also sec loop (page 350), a general iteration facility based on a keyword syntax rather than a list- 
structure syntax. 
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do* Special form 

In a word, do* is to do as let* is to let. 

do* works like do but binds and steps the variables sequentially instead of in parallel. 
This means that the ///// form for one variable can use the values of previous variables. 
The repeal forms refer to the new values of previous variables instead of their old values. 
Here is an example: 

(do* ( (x xl ist (cdr x) ) 

(y (car x) (car x) ) ) 
(print (list xy))) 
On each iteration, ;'s value is the car of jr. The same construction with do might get an 
error on entry since x might not be bound yet. 

do - n ame d Special form 

do-named is like do but defines a block with a name explicitly specified by the 
programmer in addition to the block named nil which every do defines. 1 his makes it. 
possible to use return-from to return from this do-named even from within an inner do. 
An ordinary return there would return from the inner do instead, do-named is obsolete 
now that block, which is more general and more coherent, exists. See section 4.4, page 
75 for more information on block and return-from. 

ITie syntax of do-named is like do except that the symbol do-named is immediately 

followed by the block name, which should be a symbol. 

Example: 

(do-named george ((a 1 (1+ a)) 
(d *foo)) 
((> a 4) 7) 
(do ((c b (cdr c))) 
((null c)) 

(return-from george (cons b d)) 

...)) 
is equivalent to 

(block george 

(do ((a 1 (1+ a)) 
(d 'foo)) 
((> a 4) 7) 
(do ((c b (cdr c))) 
((null c)) 

(return-from george (cons b d)) 

t as the name of a do -named behaves somewhat peculiarly, and therefore should be 
avoided. 
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d o * - n arne d Spa 'nil form 

This special form offers a combination of the features of do* and those of do -named. It 
is obsolete, as is do -named, since it is cleaner to use block. 

dotimes {index count [value- expression]) body... Macro 

dotimes is a convenient abbreviation for the most common integer iteration, dotimes 
performs body the number of times given by the value of count, with index bound to 0, 
1, etc. on successive iterations. When the count is exhausted, the value of value- 
expression is returned; or nil, if value-expression is missing. 
Example: 

(dotimes (i (truncate m n)) 
(frob i)) 
is equivalent to: 

(do ((i (1+ i)) 

(count (truncate m n))) 
( (> i count)) 
(frob i)) 
except that the name count is not used. Note that i takes on values starting at zero 
rather than one, and that it stops before taking the value (truncate m n) rather dian 
after. You can use return and go and tagbody-tags inside the body, as with do. 
dotimes forms return die value of value- expression, or nil, unless returned from explicitly 
with return. For example: 
(dotimes (i 5) 

(if (eq (aref a i) *foo) 
(return i))) 
This form searches die array that is the value of a, looking for the symbol foo. It 
returns the fixnum index of the first clement of a that is foo, or else nil if none of the 
elements are foo. 

dolist (item list [value-expression]) body... Macro 

delist is a convenient abbreviation for the most common list iteration, dolist performs 
body once for each element in die list which is the value of list, with item bound to the 
successive elements. If the list is exhausted, the value of value- expression is returned; or 
nil, if value- expression is missing. 
Example: 

(dolist (item (frobs foo)) 
(mung item)) 
is equivalent to: 

(do ((1st (frobs foo) (cdr 1st)) 
(item)) 
((null 1st)) 
(setq item (car 1st)) 
(mung item)) 
except that the name 1st is not used. You can use return and go and tagbody-tags inside 
the body, as with do. 
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do-forever body... Macro 

Executes the forms in the body over and over, or until a non-local exit (such as return). 

4.4 Sialic Non-Local Exits 

The static non-local exit allows code deep within a construct to jump to the end of that 
construct instantly, not executing anything except unwind -protects on the way. The construct 
which defines a static level that can be exited non-locally is called block and the construct which 
exits it is called return -from. The block being exited must be lexically visible from the return- 
from which says to exit it; this is what 'static" means. By contrast, catch and throw provide for 
dynamic non-local exits; refer to the following section. Here is an example of using a static non- 
local exit: 

(block top 

(let ((vl (do-1))) 

(when (all-done vl) (return-from top vl)) 

(do-2)) 
(do-3) 

(do-last)) 

If (all -done v1) returns non-nil, the entire block immediately returns the value of v1. Otherwise, 
the rest of die body of the block is executed sequentially, and ultimately the value or values of 
(do-last) arc returned. 

Note that the return-from form is very unusual: it does not ever return a value itself, in the 
conventional sense. It isn't useful to write (setq a (return-from foo 3)), because when the return- 
from form is evaluated, the containing block is immediately exited, and the setq never happens. 

The fact that block's and return -from's are matched up lexically means you cannot do this: 

(defun foo (a) 
(block fool 
(bar a))) 

(defun bar (x) 

(return-from fool x)) 

The (return-from fool x) gets an error because there is no lexically visible block named fool. 
The suitable block in the caller, foo, is not even noticed. 

Static handling allows the compiler to produce good code for return-from. It is also useful 
with functional arguments: 
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(defun first-symbol (list) 
(block done 

(mapc #' ( lambda (elt) 

(if (symbolp elt) (return-from done elt))) 
list))) 

The return-from done sees the block done lexically. Kvcn if mapc had a block in it named 
done it would have no effect on the execution of first -symbol. 

When a function is defined with defun with a name which is a symbol, a block whose name 
is the function name is automatically placed around the body of the function definition. For 
example, 

{defun foo (a) 
(if (evenp a) 

(return-from foo (list a))) 
(1+ a)) 

(foo 4) => (4) 
(foo 5) => 6 

A function written explicitly with lambda docs not have a block unless you write one 
yourself. 

A named prog, or a do -named, implicitly defines a block with the specified name. So you 
can exit those constructs with return-from. In fact, the ability to name prog's was the original 
way to define a place for return-from to exit, before block was invented. 

Every prog, do or loop, whether named or not, implicitly defines a block named nil. Thus, 
named prog's define two block's, one named nil and one named whatever name you specify. As 
a result, you can use return (an abbreviation for return-from nil) to return from the innennost 
lexically containing prog, do or loop (or from a block nil if you happen to write one). This 
function is like assq, but it returns an additional value which is the index in the table of the 
entry it found. For example, 

(defun assqn (x table) 
(do ((1 table (cdr 1)) 
(n (1+ n))) 
((null 1) nil) 
(if (eq (caar 1) x) 

(return (values (car 1) n))))) 

There is one exception to this: a prog, do or loop with name t defines only the block 
named t, no block named nil. The compiler used to make use of this feature in expanding 
certain built-in constructs into others. 
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block name body... Special form 

Hxccutes body, returning the values of the last form in body, but permitting non-local 
exit using return -from forms present lexically within body, name is not evaluated, and is 
used to match up return -from forms with their block'ss. 
(block foo 

(return-from foo 24) t) => 24 
(block foo t) => t 

return-from name values Special form 

Performs a non-local exit from the innermost lexically containing block whose name is 
name, name is not evaluated. When the compiler is used, return -from's arc matched up 
with block's at compile time. 

values is evaluated and its values become the values of the exited block form. 

A return-from form may appear as or inside an argument to a regular function, but if 
the return-from is executed then the function will never actually be called. For example, 
(block done 

(foo (if a (return-from done t) nil))) 
foo is actually called only if as value is nil. This style of coding is not recommended 
when foo is actually a function. 

return-from can also be used -with zero value forms, or with several value forms. Then 
one value is returned from each value form. Originally return-from always returned only 
one value from each value form, even when there was only one value form. Passing back 
all the values when there is a single values form is a later change, which is also the 
Common Lisp standard. In fact, the single value form case is much more powerful and 
subsumes all the others. For example, 

(return-from foo 1 2) 
is equivalent to 

(return-from foo (values 1 2)) 
and 

(return-from foo) 
is equivalent to 

(return-from foo (values)) 
It is unfortunate that the case of one value form is treated differently from all other cases, 
but the power of being able to propagate any number of values from a single form is 
worth it. 

To return precisely one value, use (return-from foo (values form)). It is legal to write 
simply (return-from foo), which returns no values from the block. Sec section 3.7, page 
55 for more infonnation. 

return values Special fonn 

Is equivalent to (return-from nil values). It returns from a block whose name is nil. 

In addition, break (see page 795) recognizes the typed-in form (return value) specially, 
break evaluates value and returns it. 
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return- 11 st list Special form 

This function is like return except that each dement of list is returned as a separate value 
from the block that is exited. 

return -list is obsolete, since (return (values- list list)) docs the same thing. 

4.5 Tags and Gotos 

Jumping to a label or lag is another kind of static non-local exit. Compared with return- 
from, it allows more flexibility in choosing where to send control to, but does not allow values to 
be sent along. This is because the tag docs not have any way of saying what to do with any 
values. 

To define a tag, the tagbody special form is used. In the body of a tagbody, all lists arc 
treated as forms to be evaluated (called statements when they occur in this context). If no goto 
happens, all the forms arc evaluated in sequence and then the tagbody form returns nil. Thus, 
the statements arc evaluated only for effect. 

An clement of the tagbody's body which is a symbol is not a statement but a tag instead. It 
identifies a place in the sequence of statements which you can go to. Going to a tag is 
accomplished by the form (go tag), executed at any point lexically within the tagbody. 

go transfers control immediately to the first statement following tag in its tagbody, pausing 
only to deal with any unwind -protects that arc being exited as a result. If there are no more 
statements after tag in its tagbody, then that tagbody returns nil immediately. 

All lexically containing tagbody's arc eligible to contain the specified tag, with the innermost 
tagbody taking priority. If no suitable tag is found, an error is signaled. The compiler matches 
go's with tags at compile time and issues a compiler warning if no tag is found. Example: 
(block nil 
(tagbody 

(setq x somefrob) 
loop 

do something 

( i f some predicate (go endtag)) 
do something more 
(if (minusp x) (go loop)) 
endtag 

(return z))) 
is a kind of iteration made out of go-to's. This tagbody can never exit normally because the 
return in the last statement takes control away from it. This use of a return and block is how 
one encapsulates a tagbody to produce a non-nil value. 

It works to go from an internal lambda function to a tag in a lexically containing function, 
as in 
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(defun foo (a) 
(tagbody 
tl 
(bar r (lambda () (go tl))))) 

If bar ever invokes ils argument, control goes to t1 and bar is invoked anew. Not very useful, 
but it illustrates the technique. 

tagbody statements-and-tags... Special form 

Kxecutes all the elements of statements-ami- tags which are lists (the statements), and then 
returns nil. But meanwhile, all elements of statements-ami- tags which are symbols (the 
tags) are available for use with go in any of the statements. Atoms other than symbols 
arc meaningless in a tagbody. 

The reason that tagbody returns nil rather than the value of die last statement is that the 
designers of Common Lisp decided that one could not reliably return a value from the. 
tagbody by writing it as the last statement since some of the time the expression for the 
desired value would be a symbol rather than a list, and Uicn it would be taken as a tag 
rather than die last statement and it would not work. 

go tag Specialform 

Tlic go special form is used to "go-to" a tag defined in a lexically containing tagbody 
form (or other fomi which implicitly expands into a tagbody, such as prog, do or loop). 
tag must be a symbol. It is not evaluated. 

prog Special form 

prog is an archaic special form which provides temporary variables, static non-local exits, 
and tags for go. These aspects of prog were individually abstracted out to inspire let, 
block and tagbody. Now prog is obsolete, as it is much cleaner to use let, block, 
tagbody or all three of them, or do or loop. But prog appears in so many programs 
that it cannot be eliminated. 

A typical prog looks like (prog {variables...) body...), which is equivalent to 
(block nil 

(let (variables. . . ) 
(tagbody body. . .))) 

If the first subform of a prog is a non-nil symbol (rather than a list of variables), it is 
the name of the prog, and return -from (see page 77) can be used to return from it. A 
named prog looks like 

(prog name ( variables. . . ) body. . . ) 
and is equivalent to 

(block name 
(block nil 

(let (variables. . . ) 
(tagbody body. ..)))) 
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prog* Special form 

'I lie prog* special form is almost the same as prog. The only difference is that the 
binding and initialization of the temporary variables is done sequentially, so each one can 
depend on the previous ones. Thus, the equivalent code would use let* rather than let. 

4.6 Dynamic Non-Local Exits 

catch tag body... Special form 

catch is a special form used with the throw function to do non-local exits, first tag is 
evaluated; the result is called the lag of the catch. Then the body forms arc evaluated 
sequentially, and die values of the last form arc returned. However, if, during the 
evaluation of the body, the function throw is called with the same tag as Uic tag of the 
catch, then the evaluation of the body is aborted, and the catch form immediately 
returns the values of the second argument to throw without further evaluating the current 
body form or the rest of die body. 

The fag's are used to match up throw's with catch's, (catch 'foo fonn) catches a (throw 
'too form) but not a (throw 'bar form). It is an error if throw is done when there is no 
suitable catch (or catch-all; sec below). 

Any Lisp object may be used as a catch tag. The values t and nil for tag are special: a 
catch whose tag is one of these values catches throws regardless of tag. These arc only 
for internal use by unwind -protect and catch-all respectively. The only difference 
between t and nil is in the error checking; t implies that after a "cleanup handler" is 
executed control will be thrown again to die same tag, therefore it is an error if a specific 
catch for this tag docs not exist higher up in the stack. With nil, the error check isn't 
done. Example: 

(catch 'negative 
(values 

(mapcar #'(lambda (x) 

(cond ((minusp x) 

(throw 'negative 

(values x :negative))) 
(t (f x)) ))) 

y) 

:posi tive)) 
returns a list of f of each element of y, and :positive, if they arc all positive, otherwise 
the first negative member of y, and :negative. 

catch-continuation tag throwcont non-throwcont body... Macro 

catch-cont1nuat1on-1f cond-form lag throw-corn non-throwcont body... Macro 

The catch -continuation special fonn makes it convenient to discriminate whether exit is 

normal or due to a throw. 

The body is executed inside a catch on tag (which is evaluated). If body returns 
normally, the function non-throwcont is called, passing all the values returned by the last 
fonn in body as arguments. This function's values are returned from the catch - 
continuation. 
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If on the other hand a throw to fag occurs, the values thrown are passed to the function 
throw-cont, and its values arc returned. 

If a continuation is explicitly written as nil, it is not called at all. The arguments that 
would have been passed to it arc returned instead. This is equivalent to using values as 
the function; but explicit nil is optimized, so use that. 

catch -continuation -if dilfcrs only in that the catch is not done if the value of the cond- 
form is nil. In this case, the non-throw continuation if any is always called. 

In the general case, consing is necessary to record the multiple values, but if a 
continuation is an explicit # '(lambda ...) with a fixed number of arguments, or if a 
continuation is nil, it is open coded and die consing is avoided. 

throw lag values- form Special form 

throw is the primitive for exiting from a surrounding catch, tag is evaluated, and the 
result is matched (with eq) against the tags of all active catch'cs; the innermost matching 
one is exited. If no matching catch is dynamically active, an error is signaled. 

All the values of values- form are returned from the exited catch. 

catch'cs with tag nil always match any throw. They arc really catch-all's. So do 
catch'es with tog t, which are unwind -protects, but if the only matching catch'cs are 
these then an error is signaled anyway. This is because an unwind -protect always throws 
again after its cleanup fonns arc finished; if there is nothing to catch after the last 
unwind -protect, an error will happen Uien, and it is better to detect the error sooner. 

The values t, nil, and for tag arc reserved and used for internal purposes, nil may not 
be used, because it would cause confusion in handling of unwind -protects, t may only 
be used with "unwind -stack. and nil are used internally when returning out of an 
unwind -protect. 

•catch form tag Macro 

♦throw form tag Macro 

Old, obsolete names for catch and throw. 

sys: throw- tag-not-seen (error) Condition 

This is signaled when throw (or * unwind -stack) is used and there is no catch for the 
specified tag. The condition instance supports these extra operations: 

:tag The tag being thrown to. 

:value The value being thrown (the second argument to throw). 

:count 

:action The additional two arguments given to * unwind -stack, if that was used. 

The error occurs in the environment of the throw; no unwinding has yet taken place. 
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The proceed lypc :new-tag expects one argument, a tag to throw to instead. 

•unwind stack tag value active- frame-count action 

Ibis is a generalization of throw provided for program-manipulating programs such as the 
debugger. 

tag and value arc the same as the corresponding arguments to throw. 

A tag of t invokes a special feature whereby the entire stack is unwound, and then the 
function action is called (sec below). During this process unwind -protect's receive 
control, but catch -all's do not. This feature is provided for the benefit of system 
programs which want to unwind a stack completely. 

active- frame-count, if non-nil, is the number of frames to be unwound. The definition of 
a frame is implementation-dependent. If this counts down to zero before a suitable catch 
is found, the *unwind-stack terminates and that frame returns value to whoever called it. 
This is similar to Maclisp's freturn function. 

If action is non-nil, whenever die *unwind-stack would be ready to terminate (either due 
to active-frame-count or due to lag being caught as in throw), instead action is called with 
one argument, value. If tag is t, meaning throw out the whole way, then the function 
action is not allowed to return. Otherwise the function action may return and its value 
will be returned instead of value from the catch — or from an arbitrary function if active- 
frame-count is in use. In this case the catch does not return multiple values as it 
normally docs when thrown to. Note that it is often useful for action to be a stack-group. 

Note that if both active-frame- count and action arc nil, "unwind -stack is identical to 
throw. 

unwind -protect protected-fonn cleanup-form... Special form 

Sometimes it is necessary to evaluate a form and make sure that certain side-eflfects take 
place after the form is evaluated; a typical example is: 
(progn 

(turn -on -water -faucet) 
(hairy-function 3 nil 'foo) 
(turn-off -water-faucet)) 

The non-local exit facilities of Lisp create situations in which the above code won't work, 
however: if hairy- function should use throw, return or go to transfer control outside of 
the progn form, then (turn -off- water-faucet) will never be evaluated (and the faucet 
will presumably be lefl running). This is particularly likely if hairy-function gets an error 
and the user tells the debugger to give up and flush the computation. 

In order to allow the above program to work, it can be rewritten using unwind -protect 
as follows: 
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(unwind-protect 

(progn ( turn-on-water-faucet) 

(hairy-function 3 nil 'foo)) 
(turn-off-water-faucet) ) 
If hairy-function transfers control out of the evaluation of the unwind-protect, the 
(turn -off -water -faucet) form is evaluated during the transfer of control, before control 
arrives at the catch, block or go tag to which it is being transferred. 

If the progn returns normally, then the (turn -off- water-faucet) is evaluated, and the 
unwind-protect returns the result of the progn. 

The general form of unwind-protect looks like 
(unwind-protect 
protected- form 

cleanup-fonnl . 

cleanup- fonn2 

...) 
prolected-form is evaluated, and when it returns or when it attempts to transfer control out 
of the unwind-protect, the cleanup-forms are evaluated. The value of the unwind- 
protect is die value of protected- form . Multiple values returned by the pro tec ted- form are 
propagated back through the unwind-protect. 

The cleanup forms arc run in* the variable-binding environment that you would expect: 
that is, variables bound outside the scope of the unwind-protect special form can be 
accessed, but variables bound inside the protected- form can't be. In other words, the stack 
is unwound to the point just outside the protected- form, then the cleanup handler is run, 
and then the stack is unwound some more. 

catch-all body... Macro 

(catch-all form) is like (catch some- tag form) except that it catches a throw to any tag 
at all. Since the tag thrown to is one of the returned values, the caller of catch-all may 
continue throwing to that tag if he wants. The one thing that catch-all does not catch is 
a * unwind -stack with a tag of t. catch-all is a macro which expands into catch with a 
tag of nil. 

catch-all returns all the values thrown to it, or returned by the body, plus three 
additional values: die tag thrown to, the active- frame-count, and the action. The tag 
value is nil if the body returned normally. The last two values are the third and fourth 
arguments to ""unwind -stack (see page 82) if that was used, or nil if an ordinary throw 
was done or if the body returned normally. 

If you think you want tiiis, most likely you are mistaken and you really want unwind- 
protect. 
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4.7 Mapping 

map Jin &rcst lists 

mapl Jen &rcst lists 

mapc Jin &rcst lists 

maplist Jin &rcst lists 

map car Jin &rcst te 

ma p c o n fen &rcst to 

map can /<■// &rcst lists 

Mapping is a type of iteration in which a function is successively applied to pieces of a 
list. There are several options for the way in which the pieces of the list arc chosen and 
for what is done with the results returned by the applications of the function. 

For example, mapcar operates on successive elements of the list. As it goes down the 
list, it calls the function giving it an clement of the list as its one argument: first the car, 
then the cadr, then the caddr. etc.. continuing until the end of die list is reached. Hie 
value returned by mapcar is a list of the results of the successive calls to the function. 
An example of the use of mapcar would be mapcar'ing the function abs over die list (1 
-2 -4.5 6.0e15 -4.2), which would be written as (mapcar (function abs) '(1 -2 -4.5 
6.0e15 -4.2)). The result is (1 2 4.5 6.0e15 4.2). 

In general, the mapping functions take any number of arguments. For example, 

(mapcar f xl x2 ... xn) 
In this case / must be a function of n arguments, mapcar proceeds down the lists xl, 
x2. .... xn in parallel. The first argument to /comes from xl, the second from x2, etc. 
The iteration stops as soon as any of die lists is exhausted. (If there arc no lists at all, 
then there arc no lists to be exhausted, so /is called repeatedly without end. This is an 
obscure way to write an infinite loop. It is supported for consistency.) If you want to call 
a function of many arguments where one of die arguments successively takes on the 
values of the elements of a list and die other arguments are constant, you can use a 
circular list for the other arguments to mapcar. The function circular- list is useful for 
creating such lists; see page 93. 

There are five other mapping functions besides mapcar. maplist is like mapcar except 
that the function is applied to die list and successive cdrs of diat list rather than to 
successive elements of die list, map (or mapl) and mapc arc like maplist and mapcar 
respectively, except that they don't return any useful value. These functions are used 
when the function is being called merely for its side-effects, rather dian its returned 
values, mapcan and mapcon are like mapcar and maplist respectively, except that they 
combine die results of the function using nconc instead of list. That is, mapcon could 
have been defined by 

(defun mapcon (f x y) 

(apply 'nconc (maplist f x y))) 
Of course, this definition is less general than the real one. 

Sometimes a do or a straightforward recursion is preferable to a map; however, the 
mapping functions should be used wherever diey naturally apply because this increases the 
clarity of the code. 
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Often /is a lambda-expression, rather than a symbol; for example, 

(mapcar (function (lambda (x) (cons x something))) 
some-list) 

The functional argument to a mapping function must be a function, acceptable to 
apply— it cannot be a macro or (he name of a special form. 

Here is a table showing the relations between the six map functions. 

applies function to 



returns 





1 


successive 




successive 




1 


sublists 




elements 


its own 


1 








second 


1 


map( 1) 




mapc 


argument 


1 

-+- 




-+-- 




1 ist of the 


1 








function 


1 


maplist 




mapcar 


results 


1 








nconc of the 


1 








function 


1 


mapcon 




mapcan 


results 


1 









Note that map and mapl are synonymous, map is the traditional name of this function, 
mapl is the Common Lisp name. In Common Lisp, the function map docs something 
different and incompatible; see cli:map, page 191. mapl works the same in traditional 
Zetalisp and Common Lisp. 

There are also functions (mapatoms and mapatoms-all) for mapping over all symbols in 
certain packages. See the explanation of packages (chapter 27, page 636). 

You can also do what the mapping functions do in a different way by using loop. See 
page 350. 
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